using System;




namespace FineCollection.Intf
{

    /// <summary>
    /// Result code for the <see cref="ROrderIterator{T}.Jump"/> operation.
    /// Determines has the jump was successfully or not.
    /// </summary>
    public enum JumpResult : sbyte
    {
        /// <summary>
        /// The requested item found, 
        /// jump has positioned to the exactly requested item, so the current
        /// item is equivalent with the requested.
        /// </summary>
        Exactly = 0,
        
        /// <summary>
        /// The requested item not found,
        /// jump has positioned just after the place where the requested item can be,
        /// the current item is the nearest one that is greater than the reqiested one.
        /// </summary>
        Over = 1,

        /// <summary>
        /// The requested item not found,
        /// and no more items that are greater than the requested one,
        /// so jump has positioned at the end of the collection (behind the last
        /// element).
        /// Or the collection is empty.
        /// </summary>
        End = 2,

        /// <summary>
        /// The requested item is less than the current one,
        /// so, the current position has not been changed. 
        /// </summary>
        Before = -1
    }
    

    /// <summary>
    /// A simple read-only iterator.
    /// </summary>
    public interface ROrderIterator<T> : RIterator<T>
        where T: IComparable<T>
    {

        /// <summary>
        /// Finds the item that equals to the specified one,
        /// or (if no) the nearest item that is greater than the specified one,
        /// and move the iterator position to this item.
        /// </summary>
        /// <param name="item">an item to find (requested item), not null.</param>
        /// <returns>how this opeartion completed.</returns>
        /// <remarks>
        /// Jump notes:
        /// <list type="bullet">
        /// <item>When the current item is greater that the requested one -
        ///       this method does nothing.
        /// </item>
        /// <item>When the requested item presents in the collection (and the current
        ///       positions is not behined it) - jump locates this item exactly.
        /// </item>
        /// <item>When the requested item not found - jump locates to the nearest item
        ///       that greater than the requested one.
        /// </item>
        /// <item>When the requested item is greater that the last item of the colection -
        ///       jump locates to the end.
        /// </item>
        /// </list>
        /// </remarks>
        /// <exception cref="NullItemsException">when null requested.</exception>
        JumpResult Jump(T item);

    }

}